package org.bhf.service;

/**
 * Copyright (c) 2007, Blue Hole Software. All rights reserved.
 * Code licensed under the Apache 2.0 License:
 * http://www.apache.org/licenses/
 */

import org.bhf.service.view.JSONProcessView;
import org.bhf.util.AnnotationAccess;

import java.lang.annotation.Documented;
import java.lang.annotation.ElementType;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;

/**
 * Configuration for a Service class.
 */
@Documented
@Retention( RetentionPolicy.RUNTIME )
@Target( ElementType.TYPE )
public @interface Service
{
    /**
     * Utility accessors for <code>ServiceName</code>
     * @exclude
     */
    public static final class Util
    {
        static final Class<Service> clazz = Service.class;

        /**
         * Obtain the <code>ServiceName</code> annotation for the specified <code>Class</code>.
         * @param serviceClass the target <code>Class</code>.
         * @return the <code>ServiceName</code> annotation for the specified <code>Class</code>
         *      if it exists; otherwise <code>null</code>.
         */
        public static Service get( final Class<?> serviceClass )
        {
            return AnnotationAccess.getAnnotation( serviceClass, clazz );
        }

        /**
         * Return the name of this <code>ServiceName</code>.
         * @param serviceClass The <code>ServiceName</code> <code>Class</code>.
         * @return The name of this <code>ServiceName</code>.
         */
        public static String        getName( final Class<?> serviceClass )
        {
            // No inheritance for validators :)
            final Service serviceName = get( serviceClass );

            return serviceName != null ? serviceName.name() : null;
        }
    }

    /**
     * Return the name of this Service.
     * @return The name of this Service.
     */
    String                          name();

    /**
     * Default <code>ProcessView</code> for method return results. The default is <code>JSONProcessView</code>.
     * @return Default <code>ProcessView</code> for method return results.
     */
    Class<? extends ProcessView>    view() default JSONProcessView.class;

    /**
     * A list of roles, by name, that are allowed to access this service. Can be overridden at the method. The
     * special role name "ANY" implies all roles.
     * @return A list of roles, by name, that are allowed to access this service.
     */
    String[]                        roles() default "ANY";

    /**
     * If <code>true</code>, allow cross site invocations of this Service: default is false. Cross site Services are
     * vunerable to Cross Site Request Forgery (CSRF) attacks and must nver depend, directly or indirectly, on cookies
     * for security. This property can be overridden at the method level.
     * @return <code>true</code>, allow cross site invocations of this method.
     */
    boolean                         crossSite() default false;
}
